Sphere function documentation


Go here for language specification: http://www.mozilla.org/js/language/


Descriptions by Rizen
Many thanks!
Edited and updated by Darklich and AegisKnight :)



*** general functions ***
GetVersion()
  - Returns the current version of Sphere as a floating point number
    (e.g. 1.0 or 1.1)

*** script functions ***
EvaluateScript(script)
  - Reads the script in and uses it as if it were a part of the current script.
    ex: EvaluateScript("myscript.js");

EvaluateSystemScript(script)
  - Reads in one of the preset system scripts for use in the current script
    ex: EvaluateSystemScript("menu.js");

RequireScript(script)
  - Reads the script in and uses it as if it were a part of the current script.
    But only if the script has not already been evaluated.
    ex: RequireScript("myscript.js");

RequireSystemScript(script)
  - Reads in one of the preset system scripts for use in the current script.
    But only if the script has not already been evaluated.
    ex: RequireSystemScript("menu.js");

GarbageCollect()
  - invokes the JavaScript garbage collector


*** miscellaneous ***

CreateStringFromCode(code)
  - creates a single-character string based on the code passed in, i.e. 65 is "A"



*** engine functions ***

GetVersionString()
  - Returns the current Sphere version string

GetGameList()
  - Returns array of game objects
    - game.name          Name of game
    - game.directory     Directory (project name) where game is stored
    - game.author        Who wrote it?
    - game.description   Bite-sized summary of game.

ExecuteGame(directory)
  - executes the game in sphere/games/<directory>.  This function
    actually exits the first game and loads the one in 'directory'.
    When the second game returns, the original is loaded again.  (Note
    that this is unlike Sphere 0.97, which returned directly from
    ExecuteGame when the other game finished.)

RestartGame()
  - restarts the current game

Exit()
  - Exits the Sphere engine unconditionally

Abort(message)
  - Exits the Sphere engine unconditionally, displays the 'message' to the 
    user
    If you end the message with a newline it wont display the file/line
    where the Abort occured.
    e.g. Abort("Mistake here")
     vs. Abort("Game over!\n");


*** debugging (the log object) ***
OpenLog(filename)
  - opens a log file for use under the filename. If Sphere is unable to open 
    the file for logging, the engine will give an error message and exit. 
    If Sphere is successful in opening the file, it will return a log object
    for use.
    ex: var myLog = OpenLog("game.log");

log_object.write(text)
  - writes a string of text under the current block.
    ex: myLog.write("Starting system...");

log_object.beginBlock(name)
  - creates a "block" which is indent inside the log with the name as the 
    title of the block. Any subsequent write commands will go under the newly 
    created block.
    ex: myLog.beginBlock("Video Information");

log_object.endBlock()
  - closes the current log block.



*** system interfaces ***

  *** video ***
  FlipScreen()
    - displays the contents from the video buffer onto the screen. Then the 
      video buffer is cleared. You *need* to call this to make anything 
      you've drawn in code to appear on the screen.
  
  SetClippingRectangle(x, y, w, h)
    - Sets a clipping rectangle of width w and height h at (x, y) into the 
      video buffer. Anything drawn outside the rectangle is not drawn into 
      the video buffer.
      
   GetClippingRectangle()
     - Returns a rectangle object representing the clipping rectangle.
       i.e.
       var clip = GetClippingRectangle();
           clip.x
           clip.y
           clip.width
           clip.height
  
  ApplyColorMask(color)
    - fills the whole screen with the color specified. Note that the color
      passed must have an alpha that is less than 255. Otherwise, it'll 
      just make the screen solidly that color.
      ApplyColorMask tints the screen's current state
      (meaning you'll have to call it every frame
       if you want the effect to be permanent)
  
  SetFrameRate(fps)
    - allows you to set the maximum frames rendered per second that 
      the engine is allowed to draw at most.  Set to 0 in order to
      unthrottle the graphics renderer.  Keep in mind that this
      is not for the map engine, which uses the fps specified in the
      MapEngine() call.  This function only controls standard drawing
      functions and FlipScreen() outside of the map engine.  In short,
      don't use this function if you plan to be doing rendering in your
      own scripts in the map engine.
  
  GetFrameRate()
    - Returns the current fps (set by SetFrameRate... note: this is
      not the same as the map engine frame rate)
  
  GetScreenWidth()
    - returns the width of the engine screen
  
  GetScreenHeight()
    - returns the height of the engine screen


    *** graphic primitives ***
    NOTE: Make sure to use FlipScreen() when you're done drawing

    
    Point(x, y, color)
      - plots a point onto the video buffer at (x, y) with the color
    
    Line(x1, y1, x2, y2, color)
      - draws a line from (x1, y1) to (x2, y2) with the color
    
    GradientLine(x1, y1, x2, y2, color1, color2)
      - Draws a line from (x1, y1) to (x2, y2) with a color fade from color1 
        to color2
    
    Triangle(x1, y1, x2, y2, x3, y3, c)
      - Draws a filled triangle with the points (x1, y1), (x2, y2), (x3, y3), 
        with the color c
    
    GradientTriangle(x1, y1, x2, y2, x3, y3, c1, c2, c3)
      - Draws a gradient triangle with the points (x1, y1), (x2, y2), (x3, y3),
        with each point (c1 = color of (x1, y1), c2 = color of (x2, y2), c3 = color
        of (x3, y3)) having a color to generate the gradient of the triangle
    
    Rectangle(x, y, w, h, c)
      - Draws a rectangle at (x, y) of width w and height h, filled with color c.
    
    GradientRectangle(x, y, w, h, c_ul, c_ur, c_lr, c_ll)
      - Draws a gradient rectangle at (x,y) with the height h and width w.
        Each corner of a rectangle (c_ul = color of upper left corner, 
        c_ur = color of upper right corner, c_lr = color of lower right corner,
        c_ll = color of lower left corner) accepts a color information to 
        generate the gradient of the rectangle.


  *** input ***


    *** keyboard ***
    AreKeysLeft()
      - returns true or false depending if the there are keys from the key 
        input queue.
    
    GetKey()
      - returns the first key in the queue. If there are no keys in the queue,
        Sphere will wait until there is a key in the queue.
    
    IsKeyPressed(key)
      - checks if the key has been pressed. Returns true if 'key' is
    pressed....

    IsAnyKeyPressed()
      - checks if any key is pressed at the time.

    GetKeyString(key, shift)
      - converts the key into a string, KEY_A will become "a", etc.
      - if shift is true, returns uppercase/special value of key
      - control keys return ""
 
 
    *** mouse ***
    SetMousePosition(x, y)
      - Sets the x and y of the mouse cursor
    
    GetMouseX()
    GetMouseY()
      - returns the location of the mouse cursor within the engine screen
    
    IsMouseButtonPressed(button)
      - returns true if the button is pressed
        allowed button values are: MOUSE_LEFT, MOUSE_RIGHT, MOUSE_MIDDLE


    *** joystick ***
    GetNumJoysticks()
      - returns the number of joysticks available on the system

    GetJoystickX(joy)
    GetJoystickY(joy)
      - returns the current joystick position in normalized
        coordinates from -1 to 1 on both axes.

    GetNumJoystickButtons(joy)
      - returns the number of buttons available on this joystick

    IsJoystickButtonPressed(joy, button)
      - returns true if the button on joystick 'joy' is pressed


  *** time ***
  GetTime()
    - returns the number of milliseconds since some arbitrary time.
      ex:
       var start = GetTime();
       while (GetTime() < start + 1000) {}

  *** MapEngine object ***
  GetMapEngine()
    - returns the mapengine object currently being used by the map engine.
   
  mapengine_object.save(filename)
    - saves the map to filename


  *** ByteArray object ***
  ByteArrays are pretty much only used for networking (see below for Network 
  stuff) or RawFiles (also below)
  
  CreateByteArray(size)
    - returns a ByteArray object of 'size' bytes
  
  CreateByteArrayFromString(string)
    - returns a ByteArray object from string 'string'
  
  CreateStringFromByteArray(array)
    - returns a string from a ByteArray

  bytearray.length
    - the length of the byte array
  
  bytearray_object[index]
    - returns the allows you to access the index in the array

  bytearray.concat(bytearray_to_append)
    - returns bytearray with bytearray_to_append attached to the end of it

  bytearray.slice(start [, end])
    - returns a slice of the bytearray starting at start, and ending at end
      or the end of the bytearray if end is omitted.
      If end is a negative number, the end point is started from the end of the bytearray.

    *** MD5 fingerprinting ByteArray objects ***
    HashByteArray(byte_array)
      - generates an MD5 fingerprint as a hexadecimal string whose output
        is the same as the RSA reference implementation of RFC 1321 which
        means that the unix md5 command will return the same string for the
        identical input.  The resulting string contains the hexadecimal
        representation of the MD5 fingerprint for the specified byte
        array object

  *** networking ***
  GetLocalName()
    - returns a string with the local name of your computer
  
  GetLocalAddress()
    - returns a string with the IP address of your computer
  
  OpenAddress(address, port)
    - attempts to open a connection to the computer specified with 'address' on 'port'
      returns a socket object
 
  ListenOnPort(port)
    - listens for connections on port, returns a socket object if successful
  
  socket.isConnected()
    - returns true if the socket is connected
 
  socket.getPendingReadSize()
    - returns the size of the next array to be read in the socket
  
  socket.write(byte_array)
    - writes a ByteArray object into the socket
  
  socket.read(int size) 
    - reads from the socket, returns a ByteArray object

  socket.close()
    - closes the socket object, after this, the socket cannot be used.

  
*** sphere objects ***


  *** colors ***
  CreateColor(r, g, b [, a])
    - returns a color object with the color r is Red, g is Green, b is Blue,
      and a is alpha (translucency of the color). 
      Note + alpha of 0 = transparent, alpha of 255 = opaque
           + alpha is optional, and defaults to 255 if not specified
  
  BlendColors(c1, c2)
    - returns a color object that is the blended color of color c1 and c2
  
  BlendColorsWeighted(c1, c2, c1_weight, c2_weight)
    - blends two colors together, allowing you to specify the amount of each color
      ex:
      BlendColorsWeighted(a, b, 1, 1) // equal amounts (like BlendColors())
      BlendColorsWeighted(a, b, 1, 2) // 33% a, 66% b
  
  color_object.red
    - the red component of a color object
  
  color_object.green
    - the green component of a color object
  
  color_object.blue
    - the blue component of a color object
  
  color_object.alpha
    - the alpha (translucency) component of a color object
  
  + all color components are from 0-255 (unsigned 8-bits each, 4x8bit == 32bit)


  /* maps */
  
  MapEngine(map, fps)
    - starts the map engine with the map specified and runs at 'fps' frames per second
  
  ChangeMap(map)  
    - changes current map
    
  GetCurrentMap()
    - Returns the current map, e.g. "noisyforest.rmp"
    
  ExitMapEngine()
    - Exits the map engine.  Note:  This tells the map engine to shut
      down.  This does not mean the engine shuts down immediately.  You
      must wait for the original call to MapEngine() to return before you
      can start a new map engine.

  IsMapEngineRunning()
    - Returns true if the map engine is running, false if not

  UpdateMapEngine()
    - updates map engine (state of entities, color masks, etc.)

  SetMapEngineFrameRate(fps)
    - Sets the max frame rate (in frames per second) that the map engine will go at

  GetMapEngineFrameRate()
    - Returns the current map engine frames per second rate set by either MapEngine(map, fps) or SetMapEngineFrameRate(fps)
  
  CallMapScript(which)
    - calls a map's script from code
    the six events are:
      SCRIPT_ON_ENTER_MAP
      SCRIPT_ON_LEAVE_MAP
      SCRIPT_ON_LEAVE_MAP_NORTH
      SCRIPT_ON_LEAVE_MAP_EAST
      SCRIPT_ON_LEAVE_MAP_SOUTH
      SCRIPT_ON_LEAVE_MAP_WEST
  
  SetDefaultMapScript(which, script)
    - set the default script that the map engine should call before calling the map's specific script
    (The default map script is called, then the map specific script is called.)
    The events are the same from CallMapScript.
    The map engine doesn't have to be on to set a default script.
  
  CallDefaultMapScript(which)
    - call the default map script
    The events are the same from CallMapScript.
    The map engine doesn't have to be on to call a default script.
  
    *** maps ***

    GetNumLayers()
      - get number of layers on map
      - in the following functions, layer 0 is the bottommost layer.
      - layer 1 is the next one up, etc.

    GetLayerName(layer_index)
      - returns the name of 'layer'

    GetLayerWidth(layer_index)
      - get width of 'layer'

    GetLayerHeight(layer_index)
      - get height of 'layer'

    IsLayerVisible(layer_index)
      - returns true if the layer is visible

    SetLayerVisible(layer_index, visible)
      - shows 'layer_index' if visible == true, and hides it if visible == false
      e.g. SetLayerVisible(0, !IsLayerVisisble(0)); will toggle layer zero's visibility

     IsLayerReflective(layer_index)
      - returns true if the layer is reflective

    SetLayerReflective(layer_index, reflective)
      - sets whether layer should be reflective

    SetLayerMask(layer_index, mask)
      - set the color mask of 'layer' to 'mask'
      e.g. SetLayerMask(0, CreateColor(255, 0, 0, 128)); will make the layer semi red

    GetLayerMask(layer_index)
      - get the color mask currently being used by 'layer'

    SetLayerScaleFactorX(layer_index, factor_x)
      - Sets the x zoom/scale factor for the layer 'layer_index' to 'factor_x'
        e.g. SetLayerScaleFactor(0, 0.5); will make the layer zoom out to half the normal size

    SetLayerScaleFactorY(layer_index, factor_y)
      - Sets the y zoom/scale factor for the layer 'layer_index' to 'factor_y'
        e.g. SetLayerScaleFactor(0, 2); will make the layer zoom in to twice the normal size

    GetLayerAngle(layer_index)
      - Gets the angle (in radians) for the layer 'layer_index'
        e.g. var angle = GetLayerAngle(0) will get the angle for the first layer
        An angle of 0.0 is not rotated at all.

    SetLayerAngle(layer_index, angle)
      - Sets the angle (in radians) for the layer 'layer_index' to 'angle'
        e.g. SetLayerAngle(0, Math.PI) will make the layer rotate slightly

    GetNumTiles()
      - return number of tiles in map

    SetTile(x, y, layer, tile)
      - changes tile on map to 'tile'

    GetTile(x, y, layer)
      - returns tile on map

    GetTileName(tile_index)
      - returns the name of the tile 'tile_index'

    GetTileWidth()
      - returns width in pixels of tiles on current map

    GetTileHeight()
      - returns height in pixels of tiles on current map

    GetTileImage(tile_index)
      - returns the image of the tile 'tile_index'
      
    SetTileImage(tile_index, image_object)
      - sets the tile 'tile_index' to the image 'image_object'

    GetTileSurface(tile_index)
      - returns the surface of the tile 'tile_index'
      
    SetTileSurface(tile_index, surface_object)
      - sets the tile 'tile_index' to the surface 'surface_object'
      
    GetTileDelay(tile)
      - gets the animation delay of the tile 'tile'
        If it returns 0, the tile is not animated

    SetTileDelay(tile, delay)
      - sets the animation delay of the tile 'tile' to 'delay'
        A delay of 0 is considered not animated

    GetNextAnimatedTile(tile)
      - gets the next tile in the animation sequence of 'tile'
        Note that if the return value is 'tile' the tile is not animated.
      
    SetNextAnimatedTile(tile, next_tile)
      - sets the next tile in the animation sequence of 'tile' to 'new_tile'
        SetNextAnimatedTile(tile, tile) turns off the tile animation for 'tile'

    ReplaceTilesOnLayer(layer, oldtile, newtile)
      - Replaces all 'oldtile' tiles with 'newtile' on layer 'layer'
      
    IsTriggerAt(map_x, map_y, layer)
      - Returns true if there is a trigger at map_x, map_y on layer.  map_x
        and map_y are in map (per-pixel) coordinates.
        (Currently the layer parameter is ignored, although it still must be valid.)
      
    ExecuteTrigger(map_x, map_y, layer)
      - activates the trigger positioned on map_x, map_y, layer if one exists.
        map_x and map_y are in map (per-pixel) coordinates.

        (Currently the layer parameter is ignored, although it still must be valid.)

    AreZonesAt(map_x, map_y, layer)
      - returns true if there are any zones at map_x, map_y on layer
        (Currently the layer parameter is ignored, although it still must be valid.)

    ExecuteZones(map_x, map_y, layer)
      - executes all the zones that map_x, map_y, layer is within
        map_x and map_y are in map (per-pixel) coordinates.
        (Currently the layer parameter is ignored, although it still must be valid.)

    GetNumZones()
      - returns the amount of zones that there is

    GetCurrentZone()
        - best when called from inside a ZoneScript handler
          it will return the index of the zone for which the current script 
          is running
      
    GetZoneX(zone)
      - gets the x value of zone 'zone'

    GetZoneY(zone)
      - gets the y value of zone 'zone'

    GetZoneWidth(zone)
      - gets the width value of zone 'zone'

    GetZoneHeight(zone)
      - gets the height value of zone 'zone'

    GetZoneLayer(zone)
      - gets the layer value of zone 'zone'

    SetZoneLayer(zone, layer)
      - sets the layer value of zone 'zone'

    ExecuteZoneScript(zone)
      - executes the script for the zone 'zone'

    RenderMap()
      - Renders the map into the video buffer

    SetColorMask(color, num_frames)
      - applies a color mask to things drawn by the map engine for 'num_frames' frames

    SetDelayScript(num_frames, script)
      - in 'num_frames' frames, runs 'script'
        ex: SetDelayScript(60, "ChangeMap('forest.rmp')");
        this tells the map engine to change to forest.rmp after 60 frames

   
    *** input ***
    BindKey(key, onkeydown, onkeyup)
      - runs the 'onkeydown' script when the 'key' is pressed down and runs 
        'onkeyup' when the 'key' is released
        ex: BindKey(KEY_SPACE, "mode = 'in';", "mode = 'out';");
            refer to keys.txt for a list of key names
    
    UnbindKey(key)
      - unbinds a bound key

    BindJoystickButton(joystick, button, onbuttondown, onbuttonup)
      - runs the 'onbuttondown' script when the joystick 'button' is pressed down and runs
        'onbuttonup' when the joystick 'button' is released

    UnbindJoystickButton(joystick, button)
      - unbinds a bound joystick button

    AttachInput(person_entity)
      - makes the 'person_entity' respond to the input 
        (up = KEY_UP, down = KEY_DOWN, left = KEY_LEFT, right = KEY_RIGHT)
    
    DetachInput()
      - releases input from the attached person entity
    
    IsInputAttached()
      - returns true if a person is attached to the input
    
    GetInputPerson()
      - returns a string with the name of the person who currently holds input

    AttachPlayerInput(person_entity, player_index)
      - makes the 'person_entity' respond to the input
        Currenty player_index has to be from zero to four (max four players)
        Note: AttachInput is equilivent to AttachPlayerInput(person_entity, 0)
      
    DetachPlayerInput(person_entity)
      - releases input from the attached person entity

    SetUpdateScript(script)
    // calls 'script' after each frame (don't draw stuff in here!)

    SetRenderScript(script)
    // calls 'script' after all map layers are rendered

    SetLayerRenderer(layer, script)
      - calls the rendering 'script' after 'layer' has been rendered. Only one
        rendering script can be used for each layer of the map


    *** camera ***
    AttachCamera(person_name)
      - Attaches the camera view to specified person
    
    DetachCamera()
      - Detaches camera so it can be controlled directly
    
    IsCameraAttached()
      - returns true if the camera is attached to a person, false if the
        camera is floating
    
    GetCameraPerson()
      - returns a string with the name of the person whom the camera 
        is attached to

    SetCameraX(x)
    SetCameraY(y)
      - sets the location of the camera object on the map (the center
        of the screen if possible)
    
    GetCameraX()
    GetCameraY()
      - returns the location of the camera object on the map (the center
        of the screen if possible)

    MapToScreenX(layer, x)
    MapToScreenY(layer, y)
      - returns screen coordinates of position on map

    ScreenToMapX(layer, x)
    ScreenToMapY(layer, y)
      - returns map coordinates of position on screen

  
    *** entities ***


      *** persons ***

      GetPersonList()
        - returns an array of strings representing the current person entities

      CreatePerson(name, spriteset, destroy_with_map)
        - returns a person object with 'name' from 'spriteset'. If Sphere is 
          unable to open the file, the engine will give an error message and 
          exit. destroy_with_map is a boolean (true/false value), which the 
          spriteset is destroyed when the current map is changed if the flag 
          is set to true.
      
      DestroyPerson(name)
        - destroys the person with the name

      SetPersonX(name, x)
      SetPersonY(name, y)
      SetPersonLayer(name, layer)
        - sets the position of the person on the map
      SetPersonXYFloat(name, x, y)
        - sets the position of the person with floating point accuracy
      
      SetPersonDirection(name, direction)
      SetPersonFrame(name, frame)
        - sets which frame from which direction to display
      
      GetPersonX(name)
      GetPersonY(name)
      GetPersonLayer(name)
        - Gets the position of the person on the map.
          The position is based on the middle of the spriteset's base
          rectangle.
      GetPersonXFloat(name)
      GetPersonYFloat(name)
        - Gets the position of the person on the map in floating point 
          accuracy.
      
      GetPersonDirection(name)
      GetPersonFrame(name)
        - gets the frame and direction that are currently being displayed

      SetPersonSpeed(name, speed)
      SetPersonSpeedXY(name, speed_x, speed_y)
	- sets the speed at which a person moves at
	
      GetPersonSpeedX(name)
      GetPersonSpeedY(name)
        - gets the speed at which a person moves at

      SetPersonFrameRevert(name, delay)
	    - sets the delay between when the person last moved and returning to
          first frame. The delay is in frames. 0 disables this behaviour.

      GetPersonFrameRevert(name)
	    - gets the delay between when the person last moved and returning to
          first frame.  The delay is in frames. 0 disables this behaviour.

      SetPersonScaleFactor(name, scale_w, scale_h)
        - rescales the sprite to a certain scale specified by scale_w and scale_h.
          Scaling is determined by floating point numbers like, 1.5 would scale
          the person to 1.5 times its normal size based on his original sprite
          size.

      SetPersonScaleAbsolute(name, width, height)
        - rescales the sprite to width pixels and height pixels.

      GetPersonSpriteset(name)
        - returns the person's spriteset.

      SetPersonSpriteset(name, spriteset)
        - set's the person's spriteset to spriteset
        e.g. SetPersonSpriteset("Jimmy", LoadSpriteset("jimmy.running.rss"));

      GetPersonBase(name)
        - returns the person's base obstruction object.

      GetPersonAngle(name)
        - returns the person's angle that is used

      SetPersonAngle(name, angle)
        - sets the angle which the person should be drawn at
        Note:
          Zero is no rotation, and angles are in radians.
          It does not rotate the spritesets obstruction base.

      SetPersonMask(name, color)
        - sets a color multiplier to use when drawing sprites.  if the color is
          RGBA:(255, 0, 0, 255), only the red elements of the sprite are drawn.
          If the color is RGBA:(255, 255, 255, 128), the sprite is drawn at
          half transparency.

      GetPersonMask(name)
        - returns the person's current mask

      IsPersonVisible(name)
        - returns the person's visible status 
        

      SetPersonVisible(name, visible)
        - sets the person's visible status, true = visible, false = not visible
        e.g. SetPersonVisible(GetCurrentPerson(), !IsPersonVisible(GetCurrentPerson()));

      GetPersonData(name)
        - gets a data object assiocated with the person 'name'
        There are certain default properties/values filled in by the engine, they are:
        num_frames - the number of frames for the person's current direction
        num_directions - the number of directions for the person
        width - the width of the spriteset's current frame
        height - the height of the spriteset's current frame
        leader - the person that this person is following, or "" if no-one...
        Any other properties are free for you to fill with values

        e.g. var data = GetPersonData("Jimmy");
        var num_frames = data["num_frames"];

      SetPersonData(name, data)
        - sets the 'data' object assiocated with the person 'name'
        e.g.
        var data = GetPersonData("Jimmy");
        data["talked_to_jimmy"] = true;
        SetPersonData("Jimmy", data);

      SetPersonValue(name, key, value)
        - SetPersonValue("Jimmy", "talked_to_jimmy", true); // same as code above

      GetPersonValue(name, key)
        - GetPersonValue("Jimmy", "num_frames"); // same as previous code above

      FollowPerson(name, leader, pixels)
        - makes the sprite 'name' follow 'pixels' pixels behind sprite 'leader'.
        If this function is called like:
        FollowPerson(name, "", 0),
        the person will detach from anyone it is following.
      
      SetPersonScript(name, which, script)
        - sets 'script' as the thing 'name' does in a certain event
          the five events are
          SCRIPT_ON_CREATE
          SCRIPT_ON_DESTROY
          SCRIPT_ON_ACTIVATE_TOUCH
          SCRIPT_ON_ACTIVATE_TALK
          SCRIPT_COMMAND_GENERATOR
          (SCRIPT_COMMAND_GENERATOR will be called when the command queue for
           the person runs out (for random movement thingies, etc))
      
      CallPersonScript(name, which)
        - calls a person's script from code
         'which' constants are the same as for SetPersonScript()
      
      GetCurrentPerson()
        - best when called from inside a PersonScript handler
          it will return the name of the person for whom the current script 
          is running

      QueuePersonCommand(name, command, immediate)
        - adds a command to the person's command queue
          the commands are:
            COMMAND_WAIT
            COMMAND_ANIMATE
            COMMAND_FACE_NORTH
            COMMAND_FACE_NORTHEAST
            COMMAND_FACE_EAST
            COMMAND_FACE_SOUTHEAST
            COMMAND_FACE_SOUTH
            COMMAND_FACE_SOUTHWEST
            COMMAND_FACE_WEST
            COMMAND_FACE_NORTHWEST
            COMMAND_MOVE_NORTH
            COMMAND_MOVE_EAST
            COMMAND_MOVE_SOUTH
            COMMAND_MOVE_WEST
          (note: these *might* change in a future release
          'immediate', if true, will execute the command go right away
          if false, it will wait until the next frame)
      
      QueuePersonScript(name, script, immediate)
        - adds a script command to the person's queue
      
      ClearPersonCommands(name)
        - clears the command queue of sprite with the 'name'

      IsCommandQueueEmpty(name)
        - returns true if the person 'name' has an empty command queue

      IsPersonObstructed(name, x, y)
      // returns true if person 'name' would be obstructed at (x, y)

      GetObstructingTile(name, x, y)
      // returns -1 if name isn't obstructed by a tile at x, y,
       - returns the tile index of the tile if name is obstructed at x, y

      GetObstructingPerson(name, x, y)
      // returns "" if name isn't obstructed by person at x, y,
       - returns the name of the person if name is obstructed at x, y

      IgnorePersonObstructions(person, ignore)
       - Sets whether 'person' should ignore other spriteset bases

      IsIgnoringPersonObstructions(person)
       - Returns true if 'person' is ignoring person obstructions, else false
       
      IgnoreTileObstructions(person, ignore)
       - Sets whether 'person' should ignore tile obstructions

      IsIgnoringTileObstructions(person)
       - Returns true if 'person' is ignoring tile obstructions, else false

      GetPersonIgnoreList(person)
       - Returns a list of people that 'name' is ignoring

      SetPersonIgnoreList(person, ignore_list)
       - Tells 'person' to ignore everyone in ignore_list
       e.g. SetPersonIgnoreList("White-Bomberman", ["bomb", "powerup"]);
       Tells White-Bomberman to not be obstructed by bombs or powerups

      SetTalkActivationKey(key)
      GetTalkActivationKey()
        - set key used to activate talk scripts

      SetTalkDistance(pixels)
      GetTalkDistance()
        - set distance to check for talk script activation


  *** spritesets ***
  LoadSpriteset(filename)
    - returns a spriteset object from 'filename'. If Sphere is unable to open
      the file, the engine will give an error message and exit.

   spriteset.filename
     - the filename that the spriteset was loaded with

   spriteset.save(filename)
     - saves the spriteset object to 'filename'

   spriteset.clone()
     - returns a copy of the spriteset object

   spriteset_object.images
     - array of image objects

   spriteset_object.directions
     - array of spriteset_direction objects

   spriteset_object.base
     - spriteset_base object

  // spriteset_direction objects
  spriteset_direction.name
    - name of direction

  spriteset_direction.frames
    - array of spriteset_frame objects
  
  // spriteset_frame objects
  spriteset_frame.index
    - index into images array

  spriteset_frame.delay
    - number of frames before animation should switch

  // spriteset_base object
  base.x1 }
  base.y1 } the coordinates of the base rectangle
  base.x2 }
  base.y2 }

 
 
  *** sounds ***
  LoadSound(filename [, streaming])
    - returns a sound object from 'filename'. If Sphere is unable to open
      the file, the engine will give an error message and exit.  If the optional
      argument 'streaming' is true or unspecified, the sound is streamed from the
      hard drive.  Otherwise, it's loaded into memory.
  
  sound_object.play(repeat)
    - plays the sound. repeat is a boolean (true/false), that indicates if 
      the sound should be looped
  
  sound_object.pause()
    - pauses playback. call play() again to resume playback.

  sound_object.stop()
    - stops playback
  
  sound_object.setVolume(volume)
    - sets the volume for the sound (0-255)
  
  sound_object.getVolume()
    - returns the sound's volume (0-255)

  sound_object.setPan(pan)
    - pan can be from -255 to 255.  -255 = left, 255 = right

  sound_object.getPan()
    - returns the current pan of the sound

  sound_object.setPitch(pitch)
    - pitch ranges from 0.5 to 2.0.  0.5 is an octave down (and half as fast)
      while 2.0 is an octave up (and twice as fast).  pitch defaults to 1

  sound_object.getPitch()
    - returns the current pitch

  sound_object.isPlaying()
    - returns true if the sound is currently playing

  sound_object.isSeekable()
    - returns true if the sound is seekable
      Not all sound types are seekable, Ogg is.

  sound_object.getPosition()
    - returns the position of the sound
      returns zero if the sound isn't seekable

  sound_object.setPosition(pos)
    - sets the position of the sound
      if the sound isn't seekable, this does nothing

  sound_object.getLength()
    - gets the length of the sound

  *** fonts ***
  GetSystemFont()
    - returns a font object of the font that the engine currently uses.
  
  LoadFont(filename)
    - returns a font object from 'filename'. If Sphere is unable to open 
      the file, the engine will give an error message and exit.
  
  font_object.setColorMask(color)
    - Sets the color mask for a font (see ApplyColorMask)
  
  font_object.getColorMask()
    - Gets the color mask being used by the font object
  
  font_object.drawText(x, y, text)
    - draws 'text' at x, y with the font

  font_object.drawZoomedText(x, y, scale, text)
    - draws scaled text (1.0 = normal) with (x,y) as the upper left corner
  
  font_object.drawTextBox(x, y, w, h, offset, text)
    - draws a word-wrapped text at (x, y) with the width w and height h. The
      offset is the number of pixels which the number of pixels from y which 
      the actual drawing starts at.
    Note: 'text' can have the following special characters within it:
      \n - newline
      \t - tab
      \" - double quote
      \' - single quote
  
     For example: font_object.drawTextBox(16, 16, 200, 200, 0, "Line One\nLine Two");
  
  font_object.getHeight()
    - returns the height of the font, in pixels
  
  font_object.getStringWidth(string)
    - returns the width of a given string, in pixels

  font_object.getStringHeight(string, width)
    - returns the height of the string as if it was drawn by drawTextBox

  font_object.clone()
    - returns a copy of 'font_object'

  *** window styles ***
  GetSystemWindowStyle()
    - returns a windowstyle object of the windowstyle that the engine currently
      uses.
  
  LoadWindowStyle(filename)
    - returns a windowstyle object from 'filename'. If Sphere is unable to open
      the file, the engine will give an error message and exit.
  
  windowstyle_object.drawWindow(x, y, w, h)
    - draws the window at (x, y) with the width and height of w and h.
      Note that window corners and edges are drawn outside of the width 
      and height of the window.

   windowstyle_object.setColorMask(color)
    - sets the color mask for a windowstyle (see ApplyColorMask)

  windowstyle_object.getColorMask()
    - gets the color mask being used by the windowstyle object

  
  *** images ***
  GetSystemArrow()
    - returns an image object of the System Arrow that the engine currently uses.
  
  GetSystemUpArrow()
    - returns an image object of the System Arrow(up) that the engine currently
      uses.
  
  GetSystemDownArrow()
    - returns an image object of the System Arrow(down) that the engine 
      currently uses.
  
  LoadImage(filename)
    - returns an image object from 'filename'. If Sphere is unable to open or 
      read the image, the engine will give an error message and exit. The 
      image type that the engine supports are either PCX, BMP, JPG, and PNG.
  
  GrabImage(x, y, w, h)
    - returns an image object from a section of the video buffer 
      defined by the parameters
      (see GrabSurface)
  
  image_object.blit(x, y)
    - draws the image onto the video buffer at x,y
  
  image_object.blitMask(x, y, mask)
    - draws the image into the video buffer, except that the color passed
      as 'mask' tints the image
  
  image_object.rotateBlit(x, y, radians)
    - draws the image into the video buffer, except that the image is rotates 
      in  anti-clockwise in radians, which have a range of 0-2*pi. 
      (x,y) is the center of the blit.

  image_object.rotateBlitMask(x, y, radians, color)
    - rotateBlit + mask
  
  image_object.zoomBlit(x, y, factor)
    - draws the image into the video buffer with zooming, with the scaling 
      depending on factor. Normally a factor of 1 will blit a normal looking
      image. Between 0 and 1 will shrink the image. Any values greater than 1
      will stretch the size of the image.

  image_object.zoomBlitMask(x, y, factor, color)
    - zoomBlit + mask
  
  image_object.transformBlit(x1, y1, x2, y2, x3, y3, x4, y4)
    - draws the image into the video buffer with "transformation", where 
      (x1, y1) is the upper left corner, (x2, y2) the upper right corner, 
      (x3, y3) is the lower right corner, and (x4, y4) is the lower left 
      corner.

  image_object.transformBlitMask(x1, y1, x2, y2, x3, y3, x4, y4, mask)
    - transformBlit + blitMask

  image_object.createSurface()
    - returns a new surface object from the image
  
  image_object.width
    - the width of the image
  
  image_object.height
    - the height of the image
  
  
  *** surfaces ***
  CreateSurface(width, height, color)
    - returns a surface object with width x height, filled with color
  
  LoadSurface(filename)
    - returns a surface object with an image with the 'filename'
  
  GrabSurface(x, y, w, h)
   - returns a surface object captured from an area of the video buffer, 
     at (x, y) with the width w and height h.
     (see GrabImage)

  surface_object.width
  surface_object.height
    - dimensions

  surface_object.applyLookup(x, y, w, h, red_lookup, green_lookup, blue_lookup, alpha_lookup);
    - Apply a lookup table transformation to the pixels contained in x, y, w, h
    The lookup parameters are arrays of 256 elements containg the new pixel values.
    e.g. var invert_lookup = [255, 254, 253, 252, 251, ..., 4, 3, 2, 1, 0];
  
  surface_object.applyColorFX(x, y, w, h,  colormatrix)
	- Apply the colormatrix to the pixels contained in x, y, w, h
	  (see CreateColorMatrix)

  surface_object.applyColorFX4(x, y, w, h,  cm_upperleft, cm_upperright, cm_lowerleft, cm_lowerright)
    - Apply 4 color matrixes. Each corner has a seperate color matrix.
	  (see CreateColorMatrix)

  surface_object.blit(x, y)
    - draws the surface to the video buffer at (x,y)
  
  surface_object.blitSurface(surface, x, y)
    - draws 'surface' onto 'surface_object' at (x,y)
  
  surface_object.createImage()
    - returns an image object from the surface object
  
  surface_object.setBlendMode(mode)
    - pass it with either BLEND or REPLACE
      REPLACE mode will make the surface erase the pixels needed when doing a 
              drawing operation (setpixel, line, rectangle...)
      BLEND will blend the pixels needed when doing a drawing operation
  
  surface_object.getPixel(x, y)
    - returns the color of the pixel at (x,y)
  
  surface_object.setPixel(x, y, color)
    - sets the pixel at (x,y) to 'color'
  
  surface_object.setAlpha(alpha)
    - sets the alpha of the surface

  surface_object.replaceColor(oldColor, newColor)
    - replace all pixels of the color oldColor in the surface with newColor
  
  surface_object.line(x1, y1, x2, y2, color)
    - draws a line onto the surface starting from (x1, y1) to (x2, y2) with 
      the color
  
  surface_object.rectangle(x, y, w, h, color)
    - draws a filled rectangle onto the surface from (x, y) to (x+w, y+h)
      with 'color'
      
  surface_object.triangle(x1, y1, x2, y2, x3, y3, color)
    - draws a filled triangle with the points (x1, y1), (x2, y2), (x3, y3), 
      with 'color'
  
  surface_object.rotate(radians, resize)
    - rotates the surface anti-clockwise with the range 0 - 2*pi. The resize 
      flag is a boolean to tell the engine to resize the surface if needed
      to accomodate the rotated image.
  
  surface_object.resize(w, h)
    - resizes the surface images. This does not stretch or shrink the image
      inside the surface.
  
  surface_object.rescale(w, h)
    - stretches or shrinks the surface to the new width w and height h
  
  surface_object.flipHorizontally()
    - flips the surface horizontally
  
  surface_object.flipVertically()
    - flips the surface vertically
  
  surface_object.clone()
    - returns a surface object, which is a copy of this surface object
  
  surface_object.cloneSection(x, y, w, h)
    - returns a new surface object with the height and width of h and w, with
      part of image at (x,y) from the surface_object with the width w and 
      height h.

   surface_object.drawText(font, x, y, text)
    - draws 'text' at x, y with the font onto the surface_object

  surface_object.drawZoomedText(font, x, y, scale, text)
    - draws scaled text (1.0 = normal) with (x,y) as the upper left corner
      onto the surface_object
  
  surface_object.drawTextBox(font, x, y, w, h, offset, text)
    - draws a word-wrapped text at (x, y) onto the surface_object with the width w and height h.
      The offset is the number of pixels which the number of pixels from y which 
      the actual drawing starts at. 
      See font_object.drawTextBox for more detail.

  surface_object.save(filename)
    - saves the surface_object as an image using the filename 'filename'
      the image type is determined by the extension of the file
      e.g. surface.save("test.png") saves a png image called test.png

  *** color matrix ***
  CreateColorMatrix(rn, rr, rg, rb,  gn, gr, gg, gb,  bn, br, bg, bb)
    - Creates a colormatrix that is used to transform the colors 
	  contained in a pixel with the following formula:
        newcolor.red   = rn + (rr * oldcolor.red + rg * oldcolor.green + rb * oldcolor.blue) / 255;
        newcolor.green = gn + (gr * oldcolor.red + gg * oldcolor.green + gb * oldcolor.blue) / 255;
        newcolor.blue  = bn + (br * oldcolor.red + bg * oldcolor.green + bb * oldcolor.blue) / 255;
      (see applyColorFX and applyColorFX4)


  *** animations ***
  LoadAnimation(filename)
    - Returns an animation object with the filename. If Sphere is unable to 
      open the file, the engine will give an error message and exit. Sphere 
      supports animation formats of .flic, .fli, .flc and .mng
  
  animation_object.width
    - returns the width of the animation
  
  animation_object.height
    - returns that height of the animation
  
  animation_object.getNumFrames()
    - returns the number of frames the animation contains.  If the
      animation is an MNG file, the number of frames is unknown, and
      this function returns 0.
  
  animation_object.getDelay()
    - returns the delay between frames, in milliseconds
  
  animation_object.readNextFrame()
    - readies the next frame for drawing
  
  animation_object.drawFrame(x, y)
    - draws the current frame into the video buffer

  animation_object.drawZoomedFrame(x, y, scale);
    - draws the current frame into the video buffer with a specified
      zoom scale


  *** files ***
  GetFileList(directory)

    - directory = directory in which to enumerate files, "save" if not specified

    - returns an array of strings, which contains the filenames that resides
      in the 'directory' directory of the game.
  
  OpenFile(filename)
    - returns a file object with the filename. The file is created/loaded 
      from the "save" directory of the game. Note that any changes in the keys
      will not be saved until the file object is destroyed.
  
  file_object.read(key, default)
    - reads a value from the key
      the value type returned depends on the default value. 
      + if the default is a number, read will return a number.
      + if the default is a text or string, read will return a string.
      + if the default is a boolean, read will return a boolean
      + if the key is not present in the file, it will return the default value.
  
  file_object.write(key, value)
    - writes a value (string, number, boolean) to the file under the key name

  file_object.getNumKeys()
    - returns the number of keys in the file

  file_object.getKey(index)
    - returns a string of the key at 'index'

  file_object.flush()
    - writes the file to disk immediately...  this way you don't have
      to wait for it to save when the file object is garbage collected

  
  *** raw files ***
  OpenRawFile(filename [, writeable])
    - opens a file with the filename.
      Unless writeable is true, the file *must* exist and reside
      in the "other" directory of the game otherwise Sphere will give an error. 
      If the file is opened successfully, the function will return a rawfile
      object. If the optional argument 'writeable' is true,
      the conents of the file will be destroyed,
      and you will be able to write to the file.
    
  rawfile_object.setPosition(position)
    - sets the position that the file will be read from
  
  rawfile_object.getPosition()
    - returns the current position which the data is read from
  
  rawfile_object.getSize()
    - returns the number of bytes in the file
  
  rawfile_object.read(num_bytes)
    - reads the number of bytes that is specified by num_bytes. It will create
      and return an array of data the rawfile object has read. The array of 
      data are numbers representation of each byte (0-255). Note that if the 
      number of bytes that will be read, exceeds the filesize from the current 
      position, it will only return an array of data of that is
      actually read.  The returned object is a ByteArray, so you can do
      the same things with it as you can with any other ByteArray.

  rawfile_object.write(byte_array)
    - writes the byte array to the file at the current position
      The file must have been opened as writeable for this to work.
      
  rawfile_object.close()
    - closes the rawfile object, after this, the rawfile_object cannot be used anymore.

    *** MD5 fingerprinting rawfiles ***
    HashFromFile(filename)
      - generates an MD5 of the specified raw file, which, by backtracking
        with a ../ may refer to any file within the game directory structure.
        The result is a 32 character string containing the hexadecimal
        representation of the resulting 128-bit MD5 fingerprint.  Identical
        files produce the same MD5 hash so it is an effective way to determine
        if a file has become corrupt or altered

*** 3d Functions ***
*** All 3d functions (currently) require sphere_gl to be used as the video driver ***
SwitchProjectMode(integer)
  - Sets the drawing mode to 2d if integer is 0, 3d if 1.  All 3d drawing
    must be done while in 3d mode, and likewise for 2d.  When done drawing
    in 3d, the mode must be set back to 2d.
  
PRenderMap()
  - Renders the map as a 3d image.  

image_object.transform3DBlit(x1, y1, z1, x2, y2, z2, x3, y3, z3, x4, y4, z4)
  - Blits the image to the coordinates given.  Point 1 is the upper left
    corner of the image, 2 is the upper right, 3 is the lower right,
    and 4 is the bottom left

image_object.triangle3DBlit(sx1,sy1,x1,y1,z1,sx2,sy2,x2,y2,z2,sx3,sy3,x3,y3,z3)
  - Blits the triangle (sx1, sy1) (sx2, sy2) (sx3, sy3) part of the image, given
    in terms of the image size, to the 3 points (x1,y1,z1) (x2,y2,z2) (x3,y3,z3) 
    respectively.

Set3DCameraPosition(x,y,z)
  - Sets the 3d camera to the point (x,y,z).

Set3DCameraAngles(x_angle, y_angle, z_angle)
  - Sets the 3d camera angles to x_angle, y_angle, and z_angle, with respect
    to the corresponding x,y, and z axis.  Input is given in terms of degrees.

Get3DCameraX()
  - Returns the cameras current x position.

Get3DCameraY()
  - Returns the cameras current y position.

Get3DCameraZ()
  - Returns the cameras current z position.

Get3DCameraAngleX()
  - Returns the cameras current x angle.

Get3DCameraAngleY()
  - Returns the cameras current y angle.

Get3DCameraAngleZ()
  - Returns the cameras current z angle.
